---
title: Checkbox
package: "@chakra-ui/checkbox"
image: "components/checkbox.svg"
description:
  Checkbox component is used in forms when a user needs to select multiple
  values from several options.
---

The `Checkbox` component is used in forms when a user needs to select multiple
values from several options.

<ComponentLinks
  theme={{ componentName: "checkbox" }}
  github={{ package: "checkbox" }}
  npm={{ package: "@chakra-ui/checkbox" }}
/>

<carbon-ad></carbon-ad>

Native HTML checkboxes are 100% accessible by default, so we used a
[very common CSS technique](https://dev.to/lkopacz/create-custom-keyboard-accessible-checkboxes-2036)
to style the checkboxes.

## Import

```js
import { Checkbox, CheckboxGroup } from "@chakra-ui/react"
```

## Usage

Basic usage of `Checkbox`.

```jsx
<Checkbox defaultIsChecked>Checkbox</Checkbox>
```

### Disabled Checkbox

```jsx
<Stack spacing={10} direction="row">
  <Checkbox isDisabled>Checkbox</Checkbox>
  <Checkbox isDisabled defaultIsChecked>
    Checkbox
  </Checkbox>
</Stack>
```

### Checkbox with custom color

You can override the color scheme of the `Checkbox` to any color key specified
in `theme.colors`.

```jsx
<Stack spacing={10} direction="row">
  <Checkbox colorScheme="red" defaultIsChecked>
    Checkbox
  </Checkbox>
  <Checkbox colorScheme="green" defaultIsChecked>
    Checkbox
  </Checkbox>
</Stack>
```

### Checkbox sizes

Pass the `size` prop to change the size of the `Checkbox`. Values can be either
`sm`, `md` or `lg`.

```jsx
<HStack spacing={10} direction="row">
  <Checkbox size="sm" colorScheme="red">
    Checkbox
  </Checkbox>
  <Checkbox size="md" colorScheme="green" defaultIsChecked>
    Checkbox
  </Checkbox>
  <Checkbox size="lg" colorScheme="orange" defaultIsChecked>
    Checkbox
  </Checkbox>
</HStack>
```

### Invalid Checkbox

```jsx
<Checkbox isInvalid>Checkbox</Checkbox>
```

### Changing the spacing

We added the `spacing` prop to customize the spacing between the `Checkbox` and
label text.

```jsx live=false
<Checkbox spacing="1rem">Option</Checkbox>
```

### Changing the icon color and size

You can customize the color and size of the check icon by passing the
`iconColor` and `iconSize` prop.

```jsx live=false
<Checkbox iconColor="blue.400" iconSize="1rem">
  Option
</Checkbox>
```

### Indeterminate

```jsx
function IndeterminateExample() {
  const [checkedItems, setCheckedItems] = React.useState([false, false])

  const allChecked = checkedItems.every(Boolean)
  const isIndeterminate = checkedItems.some(Boolean) && !allChecked

  return (
    <>
      <Checkbox
        isChecked={allChecked}
        isIndeterminate={isIndeterminate}
        onChange={(e) => setCheckedItems([e.target.checked, e.target.checked])}
      >
        Parent Checkbox
      </Checkbox>
      <Stack pl={6} mt={1} spacing={1}>
        <Checkbox
          isChecked={checkedItems[0]}
          onChange={(e) => setCheckedItems([e.target.checked, checkedItems[1]])}
        >
          Child Checkbox 1
        </Checkbox>
        <Checkbox
          isChecked={checkedItems[1]}
          onChange={(e) => setCheckedItems([checkedItems[0], e.target.checked])}
        >
          Child Checkbox 2
        </Checkbox>
      </Stack>
    </>
  )
}
```

### Icon

```jsx manual=true
/**
 * 1. Create a custom icon that accepts 2 props: `isIndeterminate` and `isChecked`
 */
function CustomIcon(props) {
  const { isIndeterminate, isChecked, ...rest } = props

  const d = isIndeterminate
    ? "M12,0A12,12,0,1,0,24,12,12.013,12.013,0,0,0,12,0Zm0,19a1.5,1.5,0,1,1,1.5-1.5A1.5,1.5,0,0,1,12,19Zm1.6-6.08a1,1,0,0,0-.6.917,1,1,0,1,1-2,0,3,3,0,0,1,1.8-2.75A2,2,0,1,0,10,9.255a1,1,0,1,1-2,0,4,4,0,1,1,5.6,3.666Z"
    : "M0,12a1.5,1.5,0,0,0,1.5,1.5h8.75a.25.25,0,0,1,.25.25V22.5a1.5,1.5,0,0,0,3,0V13.75a.25.25,0,0,1,.25-.25H22.5a1.5,1.5,0,0,0,0-3H13.75a.25.25,0,0,1-.25-.25V1.5a1.5,1.5,0,0,0-3,0v8.75a.25.25,0,0,1-.25.25H1.5A1.5,1.5,0,0,0,0,12Z"

  return (
    <Icon viewBox="0 0 24 24" {...rest}>
      <path fill="currentColor" d={d} />
    </Icon>
  )
}

function CustomCheckbox() {
  return (
    <Checkbox icon={<CustomIcon />} colorScheme="cyan">
      Hello world
    </Checkbox>
  )
}

render(<CustomCheckbox />)
```

### CheckboxGroup

Chakra exports a `CheckboxGroup` component to help manage the checked state of
its children `Checkbox` components and conveniently pass a few shared style
props to each. See the props table at the bottom of this page for a list of the
shared styling props.

```jsx
<CheckboxGroup colorScheme="green" defaultValue={["naruto", "kakashi"]}>
  <HStack>
    <Checkbox value="naruto">Naruto</Checkbox>
    <Checkbox value="sasuke">Sasuke</Checkbox>
    <Checkbox value="kakashi">kakashi</Checkbox>
  </HStack>
</CheckboxGroup>
```

### Hooks

The `useCheckbox` hook is exported with state and focus management logic for use
in creating tailor-made checkbox component for your application.

The `useCheckboxGroup` hook is exported with state management logic for use in
creating tailor-made checkbox group component for your application.

## Props

### Checkbox Props

<PropsTable of="Checkbox" />

### CheckboxGroup Props

<PropsTable of="CheckboxGroup" />

#### Shared Style Props

The following style props can be set on `CheckboxGroup` and they will be
forwarded to all children `Checkbox` components.

| Name        | Type              | Default | Description                                                                                                           |
| ----------- | ----------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| colorScheme | `string`          |         | The color of the checkbox when it is checked. This should be one of the color keys in the theme (e.g."green", "red"). |
| children    | `React.ReactNode` |         | The content of the checkbox group.                                                                                    |
| size        | `sm`, `md`, `lg`  | `md`    | The size of the checkbox.                                                                                             |
| variant     | `string`          |         | The `variant` of the checkbox.                                                                                        |
